Quick Start

Get the Yucatan Public Works API running locally in minutes

Get Started in 5 Minutes

This guide will help you get the API running locally and make your first request. You’ll set up the database, start the server, and authenticate to retrieve public works data.

1. Clone the Repository

   First, clone the repository and navigate to the project directory:

   git clone <repository-url>
   cd back_sdo
   
2. Install Dependencies

   Install all required npm packages:

   npm install
   
3. Start the Database

   Use Docker Compose to launch PostgreSQL with PostGIS:

   docker-compose up -d
   

   This starts a PostgreSQL database with the PostGIS extension on port 5432.

   Make sure Docker is installed and running on your system before executing this command.

4. Configure Environment

   Create a .env file in the project root with your database credentials:

   .env

   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USER=admin
   DATABASE_PASSWORD=password123
   DATABASE_NAME=obras_yucatan_db
   

   These are the default credentials from docker-compose.yml. Change them for production use.

5. Start the Development Server

   Launch the API in development mode with auto-reload:

   npm run start:dev
   

   You should see:

   🚀 Servidor corriendo en http://localhost:3000
   

Make Your First Request

Now that the API is running, let’s authenticate and retrieve some data.

1. Login to Get a JWT Token

The API uses JWT authentication. First, obtain an access token:

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[e-mail]",
    "role": "admin"
  }
}

Save the access_token - you’ll need it for authenticated requests.

2. Retrieve Public Works

Use the token to fetch the list of obras (public works):

curl -X GET http://localhost:3000/obras \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

[
  {
    "id": 1,
    "numeroObra": 1,
    "claveUnica": "YUC-2024-001",
    "nombre": "Pavimentación de Calle Principal",
    "descripcion": "Obra de pavimentación en zona centro",
    "monto": 1500000.00,
    "municipio": {
      "id": 1,
      "nombre": "Mérida"
    },
    "estatusObra": {
      "id": 2,
      "nombre": "En Proceso"
    },
    "ejercicioFiscal": {
      "id": 1,
      "anio": 2024
    }
  }
]

3. Get a Specific Obra

Retrieve details for a single public work by ID:

curl -X GET http://localhost:3000/obras/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Understanding the Response

Each obra (public work) includes:

• numeroObra: Sequential number for the fiscal year
• claveUnica: Unique identifier for the project
• nombre: Project name
• monto: Budget amount in Mexican pesos
• municipio: Associated municipality
• estatusObra: Current project status
• ejercicioFiscal: Fiscal year
• dependencia: Government agency responsible
• ubicaciones: Geographic locations (with PostGIS data)

JavaScript

const response = await fetch('http://localhost:3000/obras', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const obras = await response.json();
console.log(obras);

Role-Based Access Control

The API implements role-based permissions:

Action	Admin	User
View obras	✅	✅
Create obra	✅	❌
Update obra	✅	❌
Delete obra	✅	❌

Only admin users can create, update, or delete obras. Regular users have read-only access.

Filtering and Pagination

The API supports query parameters for filtering:

# Filter by municipality
curl -X GET "http://localhost:3000/obras?municipioId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by status
curl -X GET "http://localhost:3000/obras?estatusObraId=2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by fiscal year
curl -X GET "http://localhost:3000/obras?ejercicioFiscalId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Next Steps

Full Installation Guide

Learn about production setup, migrations, and troubleshooting

Authentication Guide

Deep dive into JWT authentication and role management

API Reference

Explore all available endpoints and parameters

Database Schema

Understand the data model and relationships